Spring Framework 参考文档（WebSocket API）

WebSocket API

Spring Framework提供了一个WebSocket API，你可以使用它来编写处理WebSocket消息的客户端和服务器端应用程序。

`WebSocketHandler`

创建WebSocket服务器就像实现WebSocketHandler一样简单，或者更可能是扩展TextWebSocketHandler或BinaryWebSocketHandler，下面的示例使用TextWebSocketHandler：

import org.springframework.web.socket.WebSocketHandler;
import org.springframework.web.socket.WebSocketSession;
import org.springframework.web.socket.TextMessage;

public class MyHandler extends TextWebSocketHandler {

    @Override
    public void handleTextMessage(WebSocketSession session, TextMessage message) {
        // ...
    }

}

有专门的WebSocket Java配置和XML命名空间支持将前面的WebSocket处理程序映射到特定的URL，如下面的示例所示：

import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(myHandler(), "/myHandler");
    }

    @Bean
    public WebSocketHandler myHandler() {
        return new MyHandler();
    }

}

下面的示例显示了与前面示例等价的XML配置：

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:websocket="http://www.springframework.org/schema/websocket"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers>
        <websocket:mapping path="/myHandler" handler="myHandler"/>
    </websocket:handlers>

    <bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

本示例用于Spring MVC应用程序，并且应该包含在DispatcherServlet的配置中，然而，Spring的WebSocket支持不依赖于Spring MVC，在WebSocketHttpRequestHandler的帮助下，将WebSocketHandler集成到其他http服务环境中相对简单。

WebSocket握手

定制初始的HTTP WebSocket握手请求的最简单方法是通过HandshakeInterceptor，它公开握手之前和之后的方法，你可以使用这样的拦截器来阻止握手或使WebSocketSession的任何属性有效，下面的示例使用内置的拦截器将HTTP会话属性传递给WebSocket会话：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(new MyHandler(), "/myHandler")
            .addInterceptors(new HttpSessionHandshakeInterceptor());
    }

}

下面的示例显示了与前面示例等价的XML配置：

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:websocket="http://www.springframework.org/schema/websocket"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers>
        <websocket:mapping path="/myHandler" handler="myHandler"/>
        <websocket:handshake-interceptors>
            <bean class="org.springframework.web.socket.server.support.HttpSessionHandshakeInterceptor"/>
        </websocket:handshake-interceptors>
    </websocket:handlers>

    <bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

更高级的选项是扩展DefaultHandshakeHandler，该处理程序执行WebSocket握手的步骤，包括验证客户端源、协商子协议和其他细节。如果应用程序需要配置定制的RequestUpgradeStrategy以适应WebSocket服务器引擎和还不支持的版本，那么它可能还需要使用这个选项（有关此主题的更多信息，请参阅部署），Java配置和XML命名空间都使配置自定义HandshakeHandler成为可能。

Spring提供了一个WebSocketHandlerDecorator基类，你可以使用它来修饰WebSocketHandler具有额外的行为。默认情况下，在使用WebSocket Java配置或XML命名空间时，会提供并添加日志记录和异常处理实现。ExceptionWebSocketHandlerDecorator捕获来自任何WebSocketHandler的所有未捕获的异常，并以状态1011关闭WebSocket会话，这表示服务器错误。

部署

Spring WebSocket API很容易集成到Spring MVC应用程序中，其中DispatcherServlet同时服务于HTTP WebSocket握手和其他HTTP请求，通过调用WebSocketHttpRequestHandler，很容易将其集成到其他HTTP处理场景中。这很方便，也很容易理解，但是，对于JSR-356运行时，需要特别考虑。

Java WebSocket API（JSR-356）提供了两种部署机制，第一个涉及Servlet容器类路径扫描（Servlet 3特性）在启动时，另一个是Servlet容器初始化时使用的注册API。这两种机制都无法为所有HTTP处理使用单个“前端控制器” - 包括WebSocket握手和所有其他HTTP请求 - 比如Spring MVC的DispatcherServlet。

这是JSR-356的一个重要限制，Spring的WebSocket支持地址具有特定于服务器的RequestUpgradeStrategy实现，即使在JSR-356运行时运行也是如此。对于Tomcat、Jetty、GlassFish、WebLogic、WebSphere和Undertow（和WildFly），目前存在这样的策略。

已经创建了克服Java WebSocket API中上述限制的请求，可以在eclipse-ee4j/websocket-api#211中进行跟踪。Tomcat、Undertow和WebSphere提供了它们自己的API选项，可以实现这一点，Jetty也是如此，我们希望更多的服务器也能这样做。

第二个需要考虑的问题是，具有JSR-356支持的Servlet容器预计将执行ServletContainerInitializer（SCI）扫描，这可能会减慢应用程序的启动速度 — 在某些情况下，会显著降低启动速度。如果在升级到支持JSR-356的Servlet容器版本后观察到重大影响，通过使用web.xml中的<absolute-ordering />元素，应该可以选择性地启用或禁用web片段（和SCI扫描），如下例所示：

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">

    <absolute-ordering/>

</web-app>

然后可以根据名称选择性地启用web片段，比如Spring自己的SpringServletContainerInitializer，它为Servlet 3 Java初始化API提供支持，下面的示例展示了如何做到这一点：

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">

    <absolute-ordering>
        <name>spring_web</name>
    </absolute-ordering>

</web-app>

服务器配置

每个基础WebSocket引擎都公开了控制运行时特性的配置属性，比如消息缓冲区大小、空闲超时等等。

对于Tomcat、WildFly和GlassFish，你可以将ServletServerContainerFactoryBean添加到WebSocket Java配置中，如下面的示例所示：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Bean
    public ServletServerContainerFactoryBean createWebSocketContainer() {
        ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean();
        container.setMaxTextMessageBufferSize(8192);
        container.setMaxBinaryMessageBufferSize(8192);
        return container;
    }

}

下面的示例显示了与前面示例等价的XML配置：

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:websocket="http://www.springframework.org/schema/websocket"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <bean class="org.springframework...ServletServerContainerFactoryBean">
        <property name="maxTextMessageBufferSize" value="8192"/>
        <property name="maxBinaryMessageBufferSize" value="8192"/>
    </bean>

</beans>

对于客户端WebSocket配置，你应该使用WebSocketContainerFactoryBean（XML）或ContainerProvider.getWebSocketContainer()（Java配置）。

对于Jetty，需要提供预配置的Jetty WebSocketServerFactory，并通过WebSocket Java配置将其插入Spring的DefaultHandshakeHandler，下面的示例展示了如何做到这一点：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(echoWebSocketHandler(),
            "/echo").setHandshakeHandler(handshakeHandler());
    }

    @Bean
    public DefaultHandshakeHandler handshakeHandler() {

        WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER);
        policy.setInputBufferSize(8192);
        policy.setIdleTimeout(600000);

        return new DefaultHandshakeHandler(
                new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy)));
    }

}

下面的示例显示了与前面示例等价的XML配置：

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:websocket="http://www.springframework.org/schema/websocket"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers>
        <websocket:mapping path="/echo" handler="echoHandler"/>
        <websocket:handshake-handler ref="handshakeHandler"/>
    </websocket:handlers>

    <bean id="handshakeHandler" class="org.springframework...DefaultHandshakeHandler">
        <constructor-arg ref="upgradeStrategy"/>
    </bean>

    <bean id="upgradeStrategy" class="org.springframework...JettyRequestUpgradeStrategy">
        <constructor-arg ref="serverFactory"/>
    </bean>

    <bean id="serverFactory" class="org.eclipse.jetty...WebSocketServerFactory">
        <constructor-arg>
            <bean class="org.eclipse.jetty...WebSocketPolicy">
                <constructor-arg value="SERVER"/>
                <property name="inputBufferSize" value="8092"/>
                <property name="idleTimeout" value="600000"/>
            </bean>
        </constructor-arg>
    </bean>

</beans>

允许的源

在Spring Framework 4.1.5中，WebSocket和SockJS的默认行为是只接受相同源的请求，也可以允许所有或指定的源列表。这种检查主要是为浏览器客户端设计的，没有什么可以阻止其他类型的客户端修改Origin header值（请参阅RFC 6454: Web Origin概念以了解更多细节）。

三种可能的行为是：

只允许相同源的请求（默认）：在这种模式下，当启用SockJS时，Iframe HTTP响应header X-Frame-Options被设置为SAMEORIGIN，并且JSONP传输被禁用，因为它不允许检查请求的源，因此，当启用该模式时，不支持IE6和IE7。
允许指定的源列表：每个允许的源必须以http://或https://开始，在这种模式下，当启用SockJS时，IFrame传输将被禁用，因此，当启用该模式时，将不支持IE6到IE9。
允许所有的源：要启用此模式，你应该提供*作为允许的源值，在这种模式下，所有的传输都是可用的。

你可以配置WebSocket和SockJS允许的源，如下面的例子所示：

import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("http://mydomain.com");
    }

    @Bean
    public WebSocketHandler myHandler() {
        return new MyHandler();
    }

}

下面的示例显示了与前面示例等价的XML配置：

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:websocket="http://www.springframework.org/schema/websocket"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers allowed-origins="http://mydomain.com">
        <websocket:mapping path="/myHandler" handler="myHandler" />
    </websocket:handlers>

    <bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

Spring Framework 参考文档（WebSocket API）

WebSocket API

`WebSocketHandler`

WebSocket握手

部署

服务器配置

允许的源

上一篇：WebSocket介绍

下一篇：SockJS Fallback

博弈

引用和评论

Activiti 用户指南（网关）

Spring 实现 3 种异步流式接口，干掉接口超时烦恼

SpringBoot实践设计模式———装饰者模式

一个最简单的WebSocket hello world demo

Spring Boot创建定时任务

Spring Boot 中的上下文

动手使用ABAP Channel开发一些小工具，提升日常工作效率